<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="tutorial.css">
<TITLE>
Layout Rules
</TITLE>
</HEAD>
<BODY >
<A HREF="tutorial010.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial012.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H1 CLASS="chapter"><A NAME="htoc93">Appendix&nbsp;B</A>&nbsp;&nbsp;Layout Rules</H1><UL>
<LI><A HREF="tutorial011.html#toc51">General guidelines</A>
<LI><A HREF="tutorial011.html#toc52">Predicates and clauses</A>
<LI><A HREF="tutorial011.html#toc53">If-then-elses</A>
<LI><A HREF="tutorial011.html#toc54">Disjunctions</A>
<LI><A HREF="tutorial011.html#toc55">Do loops</A>
<LI><A HREF="tutorial011.html#toc56">Comments</A>
</UL>

<A NAME="layoutrules"></A>
In formulating these layout rules, we have taken certain arbitrary choices between different sensible formatting variants. While these choices work well for us, you may want to adapt a slightly different style. As long as it is done consistently (and agreed within a team), you should follow your own preferences.
<A NAME="toc51"></A>
<H2 CLASS="section"><A NAME="htoc94">B.1</A>&nbsp;&nbsp;General guidelines</H2>
Code should be indented consistently. Tabs should be every 8 spaces.
Indentation should be one tab per level of indentation<A NAME="@default287"></A>, except for
highly indented code which may be indented at 4 spaces per level of
indentation after the first.<BR>
<BR>
Each line should not extend beyond 79 characters, unless this is necessary
due to the use of long string literals. If a statement or predicate call
is too long, continue it on the next line indented two levels deeper.
If the statement or call extends over more than two lines, then make sure
the subsequent lines are indented to the same depth as the second line.
For example:
<PRE CLASS="verbatim">
Here is A_really_long_statement_that_does_not_fit +
           On_one_line + In_fact_it_doesnt_even_fit +
           On_two_lines.
</PRE>Don't put more than one statement or call on a line.<BR>
<BR>
Put spaces after commas in comma-separated lists. Put spaces either
side of infix operators. In both cases, this makes them easier to read,
particularly in expressions containing long names or names with underscores.
(There are some exceptions, such as module qualification<A NAME="@default288"></A> <CODE>foo:bar</CODE> and
functor/arity pairings <CODE>foo/3</CODE>. But not unification <CODE>X = Y</CODE> or list consing
<CODE>[Head | Tail]</CODE>.)<BR>
<BR>
Make judicious use of single blank lines in clause bodies to separate logical
components.<BR>
<BR>
<A NAME="toc52"></A>
<H2 CLASS="section"><A NAME="htoc95">B.2</A>&nbsp;&nbsp;Predicates and clauses</H2>
Keep all clauses of a predicate<A NAME="@default289"></A><A NAME="@default290"></A> in the one place. Leave at least one
blank line between the clauses of one predicate and the next (particularly
if they have similar names), since otherwise they may at first glance
appear to be all from the same predicate (of course, this never happens
because there's a comment before every predicate, right?). Similarly,
it is best not to leave blank lines between the clauses of a predicate
(particularly if done inconsistently), since otherwise at first glance
they may appear to be from different predicates.<BR>
<BR>
Clause heads should be flush against the left margin. As well as making
them easier to pick out visually, this makes it easier to grep for the
definitions of predicates (as opposed to their invocations). The head/body
separator `:-' should follow the head on the same line. The body of the
clause should then commence on the next line, indented one tab stop.
<PRE CLASS="verbatim">
non_overlap(Start1, Dur1, Start2, _Dur2):-
        Start1 + Dur1 #=&lt; Start2.
non_overlap(Start1, _Dur1, Start2, Dur2):-
        Start1 #&gt;= Start2 + Dur2.
</PRE>
<A NAME="toc53"></A>
<H2 CLASS="section"><A NAME="htoc96">B.3</A>&nbsp;&nbsp;If-then-elses</H2>
If-then-elses<A NAME="@default291"></A> should always be parenthesised. Always include the else part, even if you don't think
it's required. Always put semicolons at the start of a new line, aligned
with the opening and closing parentheses. Example:
<PRE CLASS="verbatim">
( test1 -&gt;
       goal1
;
       goal2
),
</PRE><A NAME="toc54"></A>
<H2 CLASS="section"><A NAME="htoc97">B.4</A>&nbsp;&nbsp;Disjunctions</H2>
Disjunctions<A NAME="@default292"></A> should be formatted in a similar way. Example:
<PRE CLASS="verbatim">
(
        goal1
;
        goal2
).
</PRE>
<A NAME="toc55"></A>
<H2 CLASS="section"><A NAME="htoc98">B.5</A>&nbsp;&nbsp;Do loops</H2>
Do loops<A NAME="@default293"></A> should also always be parenthesised. Loop conditions should be
listed one per line, starting after the opening parenthesis
and indented one character. The `do' keyword should be at the end of the last condition. The body of the
loop should then follow on the next line, again indented. Example:
<PRE CLASS="verbatim">
(for(J, I + 1, N),
 param(A, I) do
        Diff is J - I,
        A[I] #\= A[J],
        A[I] #\= A[J] + Diff,
        A[I] #\= A[J] - Diff
).
</PRE>
<A NAME="toc56"></A>
<H2 CLASS="section"><A NAME="htoc99">B.6</A>&nbsp;&nbsp;Comments</H2>
Every predicate should have a one line comment<A NAME="@default294"></A> documenting what it does, 
all module interfaces should be properly documented with a comment directive<A NAME="@default295"></A>.<BR>
<BR>
If an individual clause is long, it should be broken into sections, and
each section should have a <I>block comment</I><A NAME="@default296"></A> describing what it does; blank
lines should be used to show the separation into sections. Comments should
precede the code to which they apply, rather than following it.
<PRE>
%
% This is a block comment; it applies to the code in the next
% section (up to the next blank line).
%
        blah,
        blah,
        blahblah,
        blah,
</PRE>
If a particular line or two needs explanation, a <I>line</I> comment<A NAME="@default297"></A> 
<PRE>
        % This is a "line" comment; 
        % it applies to the next line or two
        % of code
        blahblah
</PRE>
or an <I>inline</I> comment<A NAME="@default298"></A> 
<PRE>
        blahblah        % This is an "inline" comment
</PRE>
should be used.<BR>
<BR>
<HR>
<A HREF="tutorial010.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial012.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
